Get GSTIN From PAN API

API Description

Objective

This API fetches the Goods and Services Tax Identification Number(GSTIN) from a business' Permanent Account Number(PAN) input.

Benefits

You can verify the legitimacy of a business or an individual by using the Get GSTIN From PAN API and can also use it to locate the state in which the business is registered.

Protocol

We recommend that HTTPS is used for all API calls. For HTTPS, only TLS v1.2 is supported to ensure better security. All data is received as JSON.

Input	Output
The ten digit PAN ID.	The GSTIN details associated with the PAN.

API URL

curl -X POST https://ind-engine.thomas.hyperverge.co/v1/fetchGSTINByPAN

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

API Request

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. A unique value representing a transaction in your business ecosystem.

Request Body

The following table provides information on the parameters used in the request body of the fetchGSTINByPAN API .

Parameter	Mandatory or Optional	Description
`pan_id`	Mandatory	The unique 10-digit alphanumeric PAN ID input. It should follow the 'CCCCCDDDDC' format 'C' represents a character and 'D' represents a digit.
`consent`	Mandatory	The parameter value should be set to `Y` in the request.

Sample Requests

The following codes are sample requests for the fetchGSTINByPAN API.

Sample Request

The following code shows a standard curl request for the fetchGSTINByPAN API.

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/fetchGSTINByPAN' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "pan_id": "<Enter_PAN_ID>",
    "consent": "Y"
}'

API Responses

Success Response
Failure Response Samples
Error Response Samples

You will receive a success response in a format similar to the following code if the API request is correct.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "status": 200,
    "data": {
      "code": "1002",
      "message": "Found 2 records",
      "results": [
        {
          "document_type": "GSTIN",
          "document_id": "<ID number of GST document>",
          "status": "Active",
          "state": "<The_State_Of_Registration>",
          "state_code": "<The_GST_State_Code>"
        },
        {
          "document_type": "GSTIN",
          "document_id": "<The_ID_number_Of_The_GST_Document>",
          "status": "Active",
          "state": "<The_State_Of_Registration>",
          "state_code": "<The_GST_State_Code>"
        }
      ]
    },
    "timestamp": 1664424036317
  }
}

Success Response Details

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "status": 200,
    "data": {
      "code": "1002",
      "message": "Found [[number]] records",
      "results": [
        {
          "document_type": "GSTIN",
          "document_id": "<ID number of GST document>",
          "status": "Active",
          "state": "<The_State_Of_Registration>",
          "state_code": "<The_GST_State_Code>"
        },
        {
          "document_type": "GSTIN",
          "document_id": "<The_ID_number_Of_The_GST_Document>",
          "status": "Active",
          "state": "<The_State_Of_Registration>",
          "state_code": "<The_GST_State_Code>"
        }
      ]
    },
    "timestamp": 1664424036317
  }
}

You will receive a failure response similar to the following code sample if the PAN input does not have a match in the database.

{
  "status": "success",
  "statusCode": "200",
  "result": {
      "status": 200,
      "data": {
          "code": "1004",
          "message": "No matching GSTIN found for the given PAN"
      },
      "timestamp": 1684756331847
  }
}

Error Response Sample - No Consent
Error Response Sample - Missing Input

You will receive an error response in a format similar to the following code if the API request is incorrect.

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "status": 400,
    "error": {
      "code": "CONSENT_NOT_GIVEN",
      "message": "Consent not provided."
    },
    "timestamp": 1664424599105
  }
}

You will receive an error response in a format similar to the following code if the API request is incorrect.

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "status": 400,
    "error": {
      "code": "BAD_REQUEST",
      "message": "Bad request.",
      "metadata": {
        "fields": [
          {
            "field": "pan_number",
            "message": "PAN number is required"
          }
        ]
      }
    },
    "timestamp": 1664424498900
  }
}

Error Response Details

An error response from the API contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Code	Error Description
400	CONSENT_NOT_GIVEN	The request did not have the `consent` input set to 'Y'.
400	BAD_REQUEST	The request is missing the mandatory PAN input.
503	UPSTREAM_SERVICE_UNAVAILABLE	The upstream source service (or government source service) was unavailable. Please restart the process.

Additionally, you might receive the following error response if the credentials used in the request are incorrect.

Status Code	Code	Error Description
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials

API Description​

Objective​

Benefits​